home *** CD-ROM | disk | FTP | other *** search
/ Developer CD Series 1993…ch: Other People's Memory / ADC Developer CD (1993-03) (''Other People's Memory'')_iso / Dev.CD Mar 93.iso / Development Platforms / Apple II / Essentials / Technical.Notes / IIGS / TN.IIGS.101 < prev    next >
Encoding:
Text File  |  1992-07-15  |  5.6 KB  |  127 lines  |  [TEXT/GEOL]
  1. Apple II
  2. Technical Notes
  3. _____________________________________________________________________________
  4.                                                   Developer Technical Support
  5. Apple IIgs
  6. #101: Patching the Toolbox
  7.  
  8. Revised by: Dave Lyons                                               May 1992
  9. Written by: Dave Lyons                                               May 1991
  10.  
  11. This Technical Note presents guidelines on when and how to patch Apple IIgs
  12. Toolbox functions.
  13.  
  14. CHANGES SINCE MAY 1991:  Added a note about patching the Tool Locator and Desk
  15. Manager, and corrected a spelling error.
  16. _____________________________________________________________________________
  17.  
  18.  
  19. INTRODUCTION
  20.  
  21. There is normally no need to patch the toolbox; avoid patching whenever you
  22. can.  If you must patch a toolbox function, be sure to have a good
  23. understanding of the call you're patching and how it interacts with the whole
  24. system.
  25.  
  26. No toolbox patch is risk-free.  Future versions of the toolbox could change in
  27. ways that make your patch less useful.  (For example, if you patched
  28. NewControl to have some global effect on controls being created, your patch
  29. became less useful when NewControl2 was introduced in System Software 5.0.)
  30.  
  31. For better compatibility, patch with care!  If any parameters passed are
  32. outside the range that was allowed when you wrote your patch, just pass the
  33. call straight through; the new toolbox probably knows something your patch
  34. doesn't.
  35.  
  36.  
  37. PATCHING THE TOOLBOX FROM AN APPLICATION
  38.  
  39. An application can easily patch a function for the duration of that
  40. application.
  41.  
  42. After starting up the tools, construct a Function Pointer Table (FPT) the same
  43. size as the existing FPT (call GetTSPtr and examine the first word of the
  44. table; multiply it by four to get the size of the FPT in bytes).  The first
  45. longword of your FPT is the number of functions in the tool set; do not
  46. hard-code this value!  Get it from the existing FPT on the fly.  Fill the rest
  47. of your FPT with zeroes, except for the functions you want to patch.  You must
  48. always patch the BootInit function (the first function) to return no error.
  49. Remember that the function pointer values are one less than the addresses of
  50. your replacement functions.
  51.  
  52. On exit, when you call TLShutDown your patch will be automatically removed.
  53. (If you're using ShutDownTools, you should call MMShutDown and TLShutDown
  54. after you call ShutDownTools.)
  55.  
  56.    Note : In the description of SetTSPtr on page 24-19 of Apple
  57.           IIgs Toolbox Reference, Volume 2, there are several
  58.           references to the TPT.  Keep in mind that the TPT is the
  59.           Toolset Pointer Table, not the Function Table Pointer
  60.           you pass to SetTSPtr.  While SetTSPtr copies the TPT to
  61.           RAM if necessary, it does not make a copy of the FPT.
  62.           After you call SetTSPtr, the FPT you passed is being
  63.           used, and any zero values in your table were filled in.
  64.  
  65.  
  66. PATCHING THE TOOLBOX FROM A DESK ACCESSORY OR SETUP FILE
  67.  
  68. A permanent initialization file or Desk Accessory can patch toolbox functions
  69. at boot time by constructing an FPT for SetTSPtr, as described for an
  70. application, but there is an extra step to make the patch "stick."
  71.  
  72. Call LoadOneTool and then SetTSPtr; then call SetDefaultTPT (see Apple IIgs
  73. Toolbox Reference Volume 3, page 51-16).
  74.  
  75. It is not safe to call SetDefaultTPT while an application is running
  76. (temporary application patches would be made permanent, and later the
  77. application would go away).  Since there are desk accessories that install
  78. other desk accessories while applications are running, desk accessory that
  79. wants to install a tool patch should make the class-one GS/OS GetName call; if
  80. the null string is returned, no application is executing yet, so it is safe to
  81. make the patch.  (Otherwise the desk accessory should ask the user to put the
  82. desk accessory file in the System:Desk.Accs folder and restart the system.)
  83.  
  84.  
  85. PATCHING THE TOOL LOCATOR OR DESK MANAGER
  86.  
  87. On ROM 3 systems, the SetTSPtr call treats toolsets 1 (Tool Locator) and 5
  88. (Desk Manager) specially, for compatibility with system software versions
  89. earlier than 5.0.
  90.  
  91. You must pass a systemOrUser value of $0001 (not $0000) when patching one of
  92. these toolsets, or the SetTSPtr call will have no effect.  Passing this
  93. special systemOrUser value works for other ROM versions, too--you don't have
  94. to check the ROM version.
  95.  
  96.  
  97. AVOID TAIL PATCHING
  98.  
  99. The best kind of patch is a pre-patch or head patch:  it does some extra work
  100. and then jumps to the original function (as found in the FPT before applying
  101. the patch).  Make sure the A, X, and Y registers contain the same values when
  102. you jump to the original function as they did when the patch got control.
  103.  
  104. A "tail patch" which calls the original function and then regains control is
  105. much more of a compatibility risk, because there are several instances where
  106. System Software patches examine return addresses to fix problems in large
  107. toolbox calls which call small ones (by patching the small one to realize it's
  108. being called from the big one, many K of RAM remain available to your
  109. application).
  110.  
  111. If you tail patch a function which the system already patched, you may prevent
  112. the toolbox from working correctly.
  113.  
  114. PATCHING THE TOOL DISPATCHER
  115.  
  116. If you need to patch a large number of functions, especially for a general
  117. purpose utility like a debugger, it may make more sense to patch the tool
  118. dispatcher vectors instead of patching individual functions.  See Apple IIgs
  119. Technical Note #87, Patching the Tool Dispatcher.
  120.  
  121.  
  122. Further Reference
  123. _____________________________________________________________________________
  124.  
  125.    o   Apple IIgs Toolbox Reference
  126.    o   Apple IIgs Technical Note #87, Patching the Tool Dispatcher
  127.